home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / terms / kermit / b / ikxdyn.hlp < prev    next >
Encoding:
Text File  |  1993-01-20  |  8.3 KB  |  184 lines
  1. IKXDYN.HLP                                             1991 June 19
  2.  
  3.             Specifications for Kermit-CICS I/O Drivers
  4.  
  5. Files of filetype PGM and SPOOL, as well as native data sets, are not
  6. handled directly by Kermit, but rather by "I/O drivers".  Filetype PGM
  7. is used for data pipes, in general, and the others are simply special
  8. cases.  The data object "name.PGM" would be moderated by CICS program
  9. "name", and all I/O operations are performed by invoking the program
  10. with a COMMAREA consisting of the Kermit File Access Block (FAB).  See
  11. below for the details of the FAB.  SPOOL files and native data sets are
  12. handled by a special driver called IKXDYNAL, but the calling sequence is
  13. the same for all drivers.  Drivers must be reentrant.  A driver could be
  14. written to handle only input or only output or both.  Upon entry to the
  15. driver, FABCOMM must contain an 8-byte operation code.  There must be a
  16. completion code in FABRESP upon return.  It should be in the style of
  17. EIBRCODE.  FABFID has the file identifier.  FABFLGS identifies the type
  18. of driver: flag FABFPGM is set for ordinary pipes, and flag FABFSPL for
  19. SPOOL files and native data sets.  The remainder of FABFID depends upon
  20. FABFLGS.
  21.  
  22. For ordinary pipes, the name of the driver is given in FABFNAM, and
  23. an optional parameter is given in FABFUID.  For files driven by
  24. IKXDYNAL, the situation is more complicated.  If FABFUID begins with an
  25. apostrophe ('), the file is an external data set specified by name; in
  26. that case, FABFNAM has the following:
  27.  
  28.     1.  F:   Ptr to current QFN buffer
  29.     2.  H:   Offset to display form of QFN
  30.     3.  H:   Length of display form
  31.  
  32. Note: the QFN buffer has the fully-qualified DSN, padded with blanks
  33. to a length of 54.  Since there appears to be no means of dynamic
  34. allocation under VSE, only MVS data set names need be considered here.
  35. The QFN may be either a normal sequential DSN or may be the name of a
  36. PDS followed by a member name in parentheses, as in P.D.S(MEMBER).
  37.  
  38. For IKXDYNAL, if FABFUID is anything else, the file is a spool file with
  39. class given by FABFUID and name given by FABFNAM.
  40.  
  41. Upon opening a file, a driver must allocate any needed storage and save
  42. the pointer in FABUWORD.  At closing, this storage must be released.
  43.  
  44. FABIOF contains 0 if the file is for input, 1 if for output.
  45.  
  46. ----------------------- Layout of FAB -----------------------------
  47. FABD     DSECT ,
  48. FABRESP  DS    XL6           Saved response code
  49. FABNORD  DS    H             Byte count of last transfer
  50. FDBD     DS    0F            Beginning of short descriptor
  51. FDBBUFF  DS    A             Buffer ptr
  52. FDBBSIZ  DS    F             Max record length
  53. FDBRCF   DS    C             Record format
  54. FDBFLGS  DS    X             Flags
  55. FDBACTV  EQU   X'80'         File is already open
  56. * SVATT  EQU   X'40'         Preserve attributes
  57. * APPN   EQU   X'10'         DISP=MOD
  58. FDBLRC   DS    H             File record length
  59. FDBSIZE  DS    F             File size in Kbytes
  60. FDBCOP   EQU   *-FDBD        Length to copy for OPEN
  61. FDBDATE  DS    XL7           Time stamp: packed yyyymmddhhmmss
  62. FABFID   DS    0CL13         File designator
  63. FABFLGS  DS    X             Flags indicating type of file
  64. FABFMAIN EQU   X'01'         Flag for MAIN TS queue
  65. FABFTS   EQU   X'02'         Flag for TS queue
  66. FABFTD   EQU   X'04'         Flag for TD queue
  67. FABFPGM  EQU   X'08'         Flag for pipe file
  68. FABFSPL  EQU   X'10'         Flag for spool file
  69. FABFTAK  EQU   X'20'         Flag for internal Kermit file
  70. FABFUID  DS    CL8           User name
  71. FABFNAM  DS    CL8           File name
  72. FABRN    DS    H             Record number
  73. FDBNREC  DS    H             Number of records
  74. FDBFL2   DS    X             More flags
  75. FDBXRCF  DS    X             External format flags
  76. FDBXLRC  DS    H             External old LRECL
  77. FDBXBLK  DS    H             External old block size
  78. FDBINFO  EQU   *-FDBD        Length of info returned
  79. FABIOF   DS    X             More flags
  80. FABLRTR  DS    F             Record length for truncation
  81. FABUWORD DS    F             Reserved for user applications
  82. FABCOMM  DS    CL8           Command name
  83. .* CLOSE     Close file named in FABFID
  84. .* CWD       Set new user directory or QFN prefix: string is at
  85. .*           FABFID+2 with 2-byte unsigned length at FABFID
  86. .* DELETE    Delete file named in FABFID
  87. .* OPEN I    Open file named in FABFID for input
  88. .* OPEN O    Open file named in FABFID for output
  89. .* READ      Read a record from (already open) file
  90. .* READ TD   Read a record from (already open) TD queue
  91. .* READ TS   Read a record from (already open) TS queue
  92. .* TEST      Check whether file named in FABFID exists
  93. .* WRIT TD   Write a record to (already open) TD queue
  94. .* WRIT TS   Write a record to (already open) TS queue
  95. .* WRITE     Write a record to (already open) file
  96.  
  97. ------------------- Scenarios that I/O drivers must handle -------------
  98.  
  99. Not all of the possible FABCOMM codes shown above would be passed to an
  100. I/O driver.  The following sequences of calls illustrate the actual
  101. codes to be expected.
  102.  
  103. ----------------------- S E N D ------------------------
  104.  
  105. 1. call with FABCOMM=CL8'TEST'.
  106.  
  107.    The file attributes should be set in FDBXRCF, FDBXLRC, and FDBXBLK
  108.    upon return (in the format of a DCT SDSCI).  BLOCKSIZE is needed only
  109.    if RECFM=U, LRECL only if RECFM is not U, and RECFM always.  Ideally,
  110.    a driver should also figure out how big the file is and save the
  111.    result in FDBSIZE and put the time stamp in FDBDATE and the number of
  112.    records in FDBNREC, but this isn't really necessary.  If the file
  113.    doesn't exist, a non-zero FABRESP should be set, and the other items
  114.    can obviously be skipped.
  115.  
  116. 2. call with FABCOMM=CL8'OPEN I'.
  117.  
  118.    The file should be allocated and opened.  If there is any problem
  119.    at all, a non-zero FABRESP should be set upon return.  The file
  120.    attributes should be set up, just as for 'TEST'.
  121.  
  122. 3. call with FABCOMM=CL8'READ'.
  123.  
  124.    FDBBUFF points to the data buffer, FABNORD gives length of buffer.
  125.    On return, FABNORD should have the actual byte count read.  If
  126.    FABRESP contains x'01' in the 1st byte on return, that signals
  127.    end-of-file; any other non-zero code is deemed an I/O error.
  128.    There should be some error code if 'READ' is used for an output
  129.    file (as indicated by FABIOF) or if the file has not been opened.
  130.  
  131. 4. call with FABCOMM=CL8'CLOSE'.
  132.  
  133.    The file should be closed and freed.
  134.  
  135. -------------------- R E C E I V E ---------------------
  136.  
  137. 1. call with FABCOMM=CL8'TEST'.
  138.  
  139.    This is the same as #1 under SEND.  If 'TEST' indicates that the file
  140.    already exists, this step might, in principle, be repeated with
  141.    different names in order to find a non-duplicate, but Kermit just
  142.    gives up at present.  The step *will* be repeated if Kermit is told
  143.    to verify storage space.
  144.  
  145. 2. call with FABCOMM=CL8'OPEN O'.
  146.  
  147.    For spool output, the file (by definition) does not exist yet.  Also,
  148.    the output attributes may be universally predefined (e.g., V/205 or
  149.    F/80).
  150.  
  151.    For disk output (possible under MVS), the action depends on the value
  152.    of FDBFLGS and on whether the file already exists.  If it does not,
  153.    or if neither APPN nor SVATT is set in FDBFLGS, then FDBLRC must be
  154.    used for the output LRECL, and FDBRCF for the output RECFM, but
  155.    BLKSIZE must be defaulted (FDBRCF "F" means "FB", and "V" means
  156.    "VB").  If the file exists, but APPN is not set, then the output must
  157.    overwrite the original file.  If APPN is set, the output must be
  158.    appended.
  159.  
  160.    In any case, the LRECL and RECFM used must be left in FDBLRC and
  161.    FDBRCF.  The file should be allocated and opened when the attributes
  162.    have been settled.  Regardless of whether all this works, a non-zero
  163.    FABRESP should be set upon return.
  164.  
  165. 4. call with FABCOMM=CL8'WRITE'.
  166.  
  167.    FDBBUFF points to the data buffer, FABNORD gives length of buffer,
  168.    as does FDBBSIZ.  If FABRESP contains x'10' in the 1st byte on
  169.    return, that signals disk-full; any other non-zero code is deemed an
  170.    unknown I/O error.  There should be some error code if 'WRITE' is
  171.    used for an input file (as indicated by FABIOF) or if the file has
  172.    not been opened.
  173.  
  174. 5. call with FABCOMM=CL8'CLOSE'.
  175.  
  176.    The file should be closed and freed.
  177.  
  178. --------------------- D E L E T E ----------------------
  179.  
  180. 1. call with FABCOMM=CL8'DELETE'.
  181.  
  182.    The file should be purged or deleted as appropriate.  If it doesn't
  183.    exist or can't be deleted, some sort of error code should be set.
  184.